METODOLOGÍA DE DESARROLLO DE SOFTWARE

Observatorio Regional de Indicadores Sociales (ORIS)

Gobierno Regional de Cusco — Gerencia de Inclusión Social, Mujer y Poblaciones Vulnerables

ÍNDICE

1. Descripción de Procesos de Negocio, Módulos y Requerimientos
2. Listado de Casos de Uso con Diagramas y Actores
3. Metodología Scrum — Burndown y Sprints
4. Matriz de Roles y Accesos

1. DESCRIPCIÓN DE PROCESOS DE NEGOCIO, MÓDULOS Y REQUERIMIENTOS {#1-descripcion}

1.1 Contexto del Negocio

El Observatorio Regional de Indicadores Sociales (ORIS) es una plataforma web institucional del Gobierno Regional de Cusco cuyo propósito es centralizar, procesar y visualizar los indicadores sociales de los 116 distritos y 13 provincias de la Región Cusco. La plataforma habilita a las 6 Unidades Funcionales a alimentar indicadores que faciliten la toma de decisiones para el cierre de brechas sociales bajo el proyecto MISIONAL.

1.2 Procesos de Negocio

Los procesos de negocio del ORIS se organizan en tres macroprocesos:

MACROPROCESO 1 — Gestión de Acceso y Seguridad

flowchart TD
    A(["👤 Funcionario"]) --> B["Ingresa credenciales\nusuario / contraseña"]
    B --> C["Sistema CAS\nvalida BCrypt"]
    C --> D{"¿MFA habilitado?"}
    D -->|SÍ| E["Solicita código TOTP\n6 dígitos / 30s"]
    D -->|NO| F["Genera JWT RS256\nAccess 15 min + Refresh 7 días"]
    E --> G["Verifica código TOTP"]
    G --> F
    F --> H(["Redirige al Dashboard Territorial"])

    style A fill:#4A90D9,color:#fff,stroke:#2c6fad
    style H fill:#27AE60,color:#fff,stroke:#1e8449
    style D fill:#F39C12,color:#fff
    style C fill:#8E44AD,color:#fff

MACROPROCESO 2 — Registro y Gestión de Indicadores Sociales

flowchart TD
    UF(["👩‍💼 Unidad Funcional"]) --> A["Accede al módulo correspondiente\nvía JWT autenticado"]
    A --> B["Registra indicadores\nfichas y datos estadísticos"]
    B --> C["Sistema valida y persiste\nen PostgreSQL"]
    C --> D["Dashboard actualiza\nen tiempo real"]
    D --> GL(["🏛️ Gobierno Local\nVisualiza indicadores territoriales"])

    style UF fill:#4A90D9,color:#fff,stroke:#2c6fad
    style GL fill:#27AE60,color:#fff,stroke:#1e8449
    style C fill:#8E44AD,color:#fff
    style D fill:#16A085,color:#fff

MACROPROCESO 3 — Reportes y Toma de Decisiones

flowchart TD
    AC(["👤 Administrador /\nUnidad Funcional"]) --> F["Selecciona filtros\nDepartamental / Provincial / Distrital"]
    F --> R["Genera reporte por\nUnidad Funcional"]
    R --> EX{"Formato de salida"}
    EX -->|PDF| P["📄 Exporta PDF"]
    EX -->|Excel| X["📊 Exporta Excel"]
    P & X --> G(["🏛️ Comparte con\nGerencia Regional"])

    style AC fill:#4A90D9,color:#fff,stroke:#2c6fad
    style G fill:#27AE60,color:#fff,stroke:#1e8449
    style EX fill:#F39C12,color:#fff
    style P fill:#E74C3C,color:#fff
    style X fill:#27AE60,color:#fff

1.3 Módulos del Sistema

El sistema ORIS se estructura en 10 módulos principales distribuidos en dos capas: infraestructura y negocio.

MÓDULO 0 — Servicio Central de Autenticación (CAS)

Microservicio: oris-cas-central | Estado: Implementado (Hito 1)

Gestiona toda la autenticación y autorización del ecosistema ORIS:

• Autenticación JWT RS256 (Access Token 15 min / Refresh Token 7 días)
• Autorización RBAC con roles macros y permisos granulares
• Autenticación Multifactor (MFA TOTP — Google Authenticator / Authy)
• CRUD de Usuarios, Roles y Permisos
• API Gateway: Rate Limiting, validación de tokens, transformación de requests

MÓDULO 1 — Tablero Observatorio Regional

Microservicio: oris-business-core | Estado: Planificado (Hito 2)

Vista principal del observatorio con:

• Panel de control con indicadores consolidados a nivel Departamental, Provincial y Distrital
• Mapa interactivo de los 116 distritos con capas de indicadores
• Filtros por Unidad Funcional, período, provincia y distrito
• Gráficos comparativos en tiempo real

MÓDULO 2 — Oficina Regional de la Mujer

Microservicio: oris-business-mujer | Estado: Planificado (Hito 2)

• Registro de indicadores de igualdad de género
• Fichas de casos de violencia familiar
• Estado de programas sociales dirigidos a mujeres
• Reportes por provincia y distrito

MÓDULO 3 — Oficina Regional de Atención a Personas con Discapacidad

Microservicio: oris-business-discapacidad | Estado: Planificado (Hito 2)

• Registro de personas con discapacidad (CONADIS)
• Seguimiento de atenciones y programas de inclusión
• Indicadores de accesibilidad por distrito
• Fichas de evaluación y seguimiento

MÓDULO 4 — Unidad Funcional del Niño, Niña y Adolescente

Microservicio: oris-business-nino-adolescente | Estado: Planificado (Hito 3)

• Indicadores de bienestar infantil
• Registro de programas DEMUNA
• Estado nutricional y acceso a educación
• Casos de vulneración de derechos

MÓDULO 5 — Unidad Funcional de Juventudes

Microservicio: oris-business-juventud | Estado: Planificado (Hito 3)

• Indicadores de empleo juvenil
• Acceso a programas de capacitación
• Participación cívica y ciudadana
• Estadísticas de deserción escolar

MÓDULO 6 — Unidad Funcional del Adulto Mayor

Microservicio: oris-business-adulto-mayor | Estado: Planificado (Hito 3)

• Registro de adultos mayores en programas sociales
• Estado de atención en centros integrales (CIAM)
• Indicadores de cobertura del programa Pensión 65
• Fichas de seguimiento de ULE

MÓDULO 7 — Unidad Funcional de Pueblos Originarios

Microservicio: oris-business-pueblo-indigena | Estado: Planificado (Hito 3)

• Registro de comunidades campesinas, nativas y rondas campesinas
• Indicadores de participación y consulta previa
• Seguimiento de programas PVL y PCA
• Mapa de comunidades originarias

MÓDULO 8 — Gestión de Reportes

Transversal a todos los módulos de negocio

• Generación de reportes por unidad funcional y por territorio
• Exportación PDF/Excel
• Dashboard de indicadores comparativos interanuales
• Alertas automáticas de brechas críticas

MÓDULO 9 — Administración del Sistema

Solo accesible para roles SUPER_ADMIN y ADMIN

• Gestión de usuarios (CRUD), asignación de roles
• Configuración de parámetros del sistema
• Auditoría y logs de actividad
• Mantenimiento de catálogos (provincias, distritos, UF)

1.4 Listado de Requerimientos

1.4.1 Requerimientos Funcionales

1.4.2 Requerimientos No Funcionales

2. LISTADO DE CASOS DE USO CON DIAGRAMAS Y ACTORES {#2-casos-de-uso}

2.1 Actores del Sistema

2.2 Diagrama General de Casos de Uso

flowchart LR
    SA("👤 SUPER_ADMIN")
    AD("👤 ADMIN")
    UF("👤 UNIDAD_FUNCIONAL")
    GL("👤 GOBIERNO_LOCAL")

    subgraph ORIS["🖥️ Sistema ORIS"]
        UC01["UC-01 Autenticarse"]
        UC02["UC-02 Configurar MFA"]
        UC03["UC-03 Gestionar Usuarios"]
        UC04["UC-04 Gestionar Roles/Permisos"]
        UC05["UC-05 Registrar Indicadores UF"]
        UC06["UC-06 Consultar Tablero Regional"]
        UC07["UC-07 Filtrar por Territorio"]
        UC08["UC-08 Generar Reportes"]
        UC09["UC-09 Administrar Catálogos"]
        UC10["UC-10 Ver Logs de Auditoría"]
    end

    SA --> UC01 & UC02 & UC03 & UC04 & UC05 & UC06 & UC07 & UC08 & UC09 & UC10
    AD --> UC01 & UC02 & UC03 & UC04 & UC06 & UC07 & UC08 & UC09
    UF --> UC01 & UC02 & UC05 & UC06 & UC07 & UC08
    GL --> UC01 & UC06 & UC07

2.3 UC-01: Autenticarse en el Sistema

Actores: SUPER_ADMIN, ADMIN, UNIDAD_FUNCIONAL, GOBIERNO_LOCAL
Precondición: Cuenta activa en el sistema
Postcondición: JWT RS256 emitido — acceso al dashboard

sequenceDiagram
    actor U as Usuario
    participant F as Frontend Angular
    participant G as API Gateway
    participant C as CAS Central
    participant D as PostgreSQL

    U->>F: Ingresa usuario y contraseña
    F->>G: POST /auth/login
    G->>C: Valida rate-limit y redirige
    C->>D: Busca OriUser + roles
    D-->>C: OriUser + roles
    C->>C: Valida BCrypt
    alt MFA Habilitado
        C-->>F: mfaRequired=true + tempToken
        U->>F: Ingresa código TOTP (6 dígitos)
        F->>C: POST /mfa/validate
        C->>C: Verifica TOTP (ventana 30s)
    end
    C->>C: Genera JWT RS256 (15 min) + Refresh (7d)
    C-->>F: accessToken + refreshToken + roles
    F-->>U: Redirige al Dashboard Territorial

2.4 UC-02: Configurar MFA (Autenticación Multifactor)

Actores: Todos los roles
Precondición: Usuario autenticado con JWT válido
Postcondición: MFA activado en la cuenta

sequenceDiagram
    actor U as Usuario Autenticado
    participant F as Frontend
    participant C as CAS Central

    U->>F: Accede a Configuración de Seguridad
    F->>C: GET /mfa/setup (Bearer JWT)
    C-->>F: qrCodeUrl + secretKey
    F-->>U: Muestra QR para escanear
    U->>U: Escanea con Google Authenticator
    U->>F: Ingresa primer código TOTP
    F->>C: POST /mfa/enable { totp }
    C->>C: Verifica y activa MFA en BD
    C-->>F: mfaEnabled: true
    F-->>U: MFA activado correctamente

2.5 UC-03: Gestionar Usuarios

Actores: SUPER_ADMIN, ADMIN
Precondición: Permiso user:create, user:read, user:update
Postcondición: Usuario creado/actualizado/desactivado

flowchart TD
    A([Admin: Gestión de Usuarios]) --> B{Acción}
    B -->|Crear| C["POST /admin/users\n{username, email, rol}"]
    B -->|Editar| D["PUT /admin/users/{id}"]
    B -->|Activar/Desactivar| E["PATCH /admin/users/{id}/status"]
    B -->|Listar| F["GET /admin/users?page=0&size=20"]
    C & D & E & F --> VAL[CAS: valida permiso user:*]
    VAL --> DB[(ori_user — PostgreSQL)]
    DB --> RES([Respuesta al Admin])

2.6 UC-04: Gestionar Roles y Permisos

Actores: SUPER_ADMIN
Precondición: Permiso role:write
Postcondición: RBAC actualizado

flowchart TD
    SA([SUPER_ADMIN]) --> R{Acción}
    R -->|Crear Rol| CR["POST /admin/roles"]
    R -->|Asignar permiso a rol| AP["POST /admin/roles/{id}/permissions"]
    R -->|Asignar rol a usuario| AU["POST /admin/users/{id}/roles"]
    R -->|Revocar rol| RR["DELETE /admin/users/{id}/roles/{roleId}"]
    CR & AP & AU & RR --> VAL[CAS: valida role:write]
    VAL --> DB[(ori_role / ori_permission\nori_user_role / ori_role_permission)]

2.7 UC-05: Registrar Indicadores por Unidad Funcional

Actores: UNIDAD_FUNCIONAL
Precondición: Autenticado con permiso indicator:write en su UF
Postcondición: Indicador persistido y visible en dashboard

sequenceDiagram
    actor UF as Especialista UF
    participant F as Frontend Angular
    participant MS as Microservicio UF
    participant C as CAS Central
    participant D as PostgreSQL

    UF->>F: Accede al módulo de su UF
    F->>C: Valida JWT y permisos
    C-->>F: Token válido + permisos UF
    UF->>F: Completa formulario de indicador
    F->>MS: POST /api/uf/{unidad}/indicadores
    MS->>C: Verifica permiso indicator:write
    C-->>MS: Autorizado
    MS->>D: INSERT en tabla de indicadores UF
    D-->>MS: Confirmación
    MS-->>F: { indicadorId, status: REGISTERED }
    F-->>UF: Registro exitoso

2.8 UC-06: Consultar Tablero Regional

Actores: Todos los roles (vista según permisos)

flowchart LR
    U([Usuario]) --> T[Dashboard Principal ORIS]
    T --> M[Mapa Interactivo\n116 Distritos / 13 Provincias]
    T --> G[Gráficos KPI por UF]
    T --> R[Ranking Territorial]
    M & G & R --> API["GET /api/dashboard/indicadores\n?uf=&provincia=&periodo="]
    API --> DB[(Vista consolidada PostgreSQL)]
    DB --> VIZ[Actualización en tiempo real]

2.9 UC-07: Filtrar Indicadores por Territorio

Actores: Todos los roles

flowchart TD
    U([Usuario]) --> SEL{Nivel territorial}
    SEL -->|Departamental| DEP[Cusco — 13 provincias]
    SEL -->|Provincial| PRO[Provincia + distritos]
    SEL -->|Distrital| DIS[Distrito específico\n+ indicadores detallados]
    DEP & PRO & DIS --> API["GET /api/indicadores\n?nivel=X&id=Y&uf=Z"]
    API --> DB[(Vista Territorial PostgreSQL)]
    DB --> CHART[Actualiza mapa y gráficos]

2.10 UC-08: Generar Reportes

Actores: SUPER_ADMIN, ADMIN, UNIDAD_FUNCIONAL
Precondición: Permiso report:generate

sequenceDiagram
    actor U as Usuario
    participant F as Frontend
    participant RS as Report Service
    participant DB as PostgreSQL

    U->>F: Selecciona tipo + filtros de reporte
    F->>RS: POST /api/reportes/generar\n{uf, provincia, periodo, formato}
    RS->>DB: Consulta datos consolidados
    DB-->>RS: Dataset filtrado
    RS->>RS: Genera PDF/Excel (JasperReports)
    RS-->>F: URL de descarga
    F-->>U: Descarga automática

2.11 UC-09: Administrar Catálogos

Actores: SUPER_ADMIN, ADMIN — Permiso catalog:write

flowchart TD
    A([Admin]) --> CAT{Catálogo a gestionar}
    CAT -->|Territorios| T[Provincias / Distritos UBIGEO]
    CAT -->|Unidades Funcionales| U[UF y especialistas]
    CAT -->|Tipos de Indicadores| I[Métricas por UF]
    CAT -->|Parámetros Sistema| P[Config. general]
    T & U & I & P --> API["PUT /admin/catalogos/{tipo}"]
    API --> DB[(Tablas catálogo PostgreSQL)]

2.12 UC-10: Ver Logs de Auditoría

Actores: SUPER_ADMIN — Permiso audit:read

flowchart LR
    SA([SUPER_ADMIN]) --> AL[Módulo de Auditoría]
    AL --> F[Filtros: usuario, acción, módulo, fecha]
    F --> API["GET /admin/audit-logs?filters"]
    API --> AZ[Azure Application Insights\n+ Log Analytics Workspace]
    AZ --> TBL["Tabla: fecha | usuario | IP | acción | resultado"]

2.13 Resumen de Casos de Uso por Actor

3. METODOLOGÍA SCRUM — BURNDOWN Y SPRINTS {#3-scrum}

3.1 Marco de Trabajo Scrum

El proyecto ORIS aplica la metodología Scrum adaptada al contexto de gobierno digital peruano, cumpliendo con la NTP-ISO/IEC 12207:2016 y la Directiva N° 03-2023-GR-CUSC/GGR. El trabajo se organiza en 4 Entregables / Hitos de 25 días cada uno, con sprints internos de 2 semanas, dentro del cronograma de 100 días calendario (09 de febrero al 18 de mayo de 2026).

Equipo Scrum ORIS

Ceremonias Scrum

3.2 Cronograma Oficial — 4 Entregables / Hitos

3.3 Product Backlog — Historias de Usuario por Entregable

Total Story Points: 254

3.4 Gráfico Gantt Oficial — Cronograma 100 Días

gantt
    title Cronograma ORIS — 100 Días (09/02/2026 al 18/05/2026)
    dateFormat  YYYY-MM-DD
    axisFormat  %d %b

    section E1 — Análisis Diseño y Base (Días 1-25)
    Revisión Prototipo y Levantamiento Req.     :done, e1a, 2026-02-09, 4d
    Diseño Arquitectura y Modelo de Datos       :done, e1b, 2026-02-13, 4d
    Backend Base, Seguridad y Roles RBAC        :done, e1c, 2026-02-17, 7d
    Base de Datos y Estructura Frontend         :done, e1d, 2026-02-24, 7d
    Pruebas Unitarias y Código Fuente E1        :done, e1e, 2026-03-03, 3d
    HITO 1 — Primer Entregable                  :milestone, h1, 2026-03-05, 0d

    section E2 — Core Unidades Funcionales (Días 26-50)
    Módulos: Mujer, Discapacidad y Niñez        :active, e2a, 2026-03-06, 9d
    Módulos: Juventudes, Adulto Mayor y Pueblos :        e2b, 2026-03-15, 8d
    Mantenimientos y Reportes Operativos        :        e2c, 2026-03-23, 5d
    Integración y Pruebas Funcionales E2        :        e2d, 2026-03-28, 3d
    HITO 2 — Segundo Entregable                 :milestone, h2, 2026-03-30, 0d

    section E3 — Dashboard y Doc. Gob. Locales (Días 51-75)
    Dashboard Gerencial e Indicadores BI        :e3a, 2026-03-31, 8d
    Manuales Técnicos y de Usuario              :e3b, 2026-04-08, 7d
    Guías de Implementación 116 Gob. Locales    :e3c, 2026-04-15, 6d
    Pruebas de Seguridad Pentest y QA           :e3d, 2026-04-21, 4d
    HITO 3 — Tercer Entregable                  :milestone, h3, 2026-04-24, 0d

    section E4 — Complementos y Cierre Final (Días 76-100)
    Integración: DEMUNA, OMAPED, CIAM y ULE     :e4a, 2026-04-25, 7d
    Integración: PVL, PCA y Complementarios     :e4b, 2026-05-02, 7d
    Capacitación y Transferencia Tecnológica    :e4c, 2026-05-09, 5d
    Despliegue Producción Hardening y Cierre    :e4d, 2026-05-14, 5d
    HITO 4 — Cuarto Entregable FINAL            :milestone, h4, 2026-05-18, 0d

3.5 Gráfico Burndown — Proyecto ORIS (100 días / 254 Story Points)

El siguiente gráfico muestra la curva ideal vs. curva real estimada por entregable:

xychart-beta
    title "Burndown Chart ORIS — 254 SP en 4 Entregables"
    x-axis ["Inicio 09-Feb", "Hito1 05-Mar Dia25", "Hito2 30-Mar Dia50", "Hito3 24-Abr Dia75", "Hito4 18-May Dia100"]
    y-axis "Story Points Pendientes" 0 --> 254
    line [254, 186, 115, 55, 0]
    line [254, 190, 118, 52, 0]

Línea 1 (ideal): Quema constante proporcional por entregable (~63 SP/hito)
Línea 2 (real estimado): E1 y E2 más intensos (arquitectura + módulos core); E3 y E4 más estables

3.6 Velocidad del Equipo por Entregable

3.7 Definición de "Hecho" (Definition of Done)

Una Historia de Usuario se considera DONE cuando cumple todos los criterios:

• Código desarrollado siguiendo Clean Architecture (Domain / Application / Infrastructure)
• Tests unitarios con cobertura ≥ 80% (JUnit 5 + Mockito)
• Tests de integración pasando en entorno Dev
• API documentada en OpenAPI 3.0 (openapi.yml actualizado)
• Pipeline CI/CD ejecutado sin errores (GitHub Actions)
• Desplegado en ambiente Dev/Cert en AKS
• Revisión de hito aprobada por el Product Owner
• Sin deuda técnica crítica (SonarQube: A en Reliability y Security)

4. MATRIZ DE ROLES Y ACCESOS {#4-roles-accesos}

4.1 Definición de Roles

4.2 Matriz de Permisos Granulares

4.3 Matriz de Acceso por Módulo/Vista

Leyenda: R = Solo Lectura | R/W = Lectura y Escritura | C/R/U/D = Crear/Leer/Actualizar/Eliminar | ❌ = Sin acceso

4.4 Matriz de Acceso a Endpoints REST (API)

4.5 Flujo de Control de Acceso (RBAC + JWT)

flowchart TD
    REQ([Request HTTP]) --> WAF[WAF v2 — OWASP Top 10]
    WAF --> APIM[API Management\nRate Limit + JWT Validation]
    APIM --> ING[Ingress Controller NGINX]
    ING --> CORS[CORS Filter]
    CORS --> JWTF[JWT Authentication Filter\nExtrae claims + roles]
    JWTF --> MFAF[MFA Verification Filter\n¿Requiere 2FA completado?]
    MFAF --> RBAC["@PreAuthorize\nhasPermission('indicador:write')"]
    RBAC -->|Permitido| CTRL[Controller — Lógica de Negocio]
    RBAC -->|Denegado| ERR403[403 Forbidden]
    CTRL --> SVC[Service Layer]
    SVC --> REPO[Repository — PostgreSQL R2DBC]
    REPO --> DB[(PostgreSQL 14)]

APÉNDICE — GLOSARIO

Documento elaborado para el Gobierno Regional de Cusco — Gerencia de Inclusión Social, Mujer y Poblaciones Vulnerables.
Cumple con: NTP-ISO/IEC 12207:2016 | Ley 29733 | Directiva N° 03-2023-GR-CUSC/GGR